Inside Macintosh: QuickDraw GX Objects /

Chapter 2 - Shape Objects / Shape Objects Reference

Functions / Drawing and Hit-Testing Shapes

GXHitTestShape

You can use the GXHitTestShape function to convert a point in space (which may represent, for example, the location of a mousedown event) into a distance from a particular part of the geometry of a shape.

gxShapePart GXHitTestShape(gxShape target, const gxPoint *test,
                       gxHitTestInfo *result);

target

A reference to the shape to hit-test.

test

A pointer to a point structure specifying the location to hit-test the shape against. The location must be specified in the local coordinates of the shape.

result

A pointer to a gxHitTestInfo structure. On return, the structure contains detailed information about the hit-test.

function result

The parts of the shape corresponding to the location specified in the test parameter (within the tolerance limits for the hit-test).

DESCRIPTION

The GXHitTestShape function takes a shape reference and a point in geometry or local space and returns whether or not the point was within a certain distance (tolerance) of one of a set of specified parts of the shape. With this function you can, for example, respond to user actions such as mouse clicks or movements by highlighting or selecting parts of shapes. The tolerance and the shape parts are defined in the hit-test parameters of the shape's transform object. The function returns the shape parts that were hit, or else the value gxNoPart if no tested part of the shape was hit.

On return, the result parameter contains a filled-out gxHitTestInfo structure. Only the first three fields are filled out by GXHitTestShape:

• The what field describes the shape parts that were hit, if any. It is identical to the function result from this function.
• The index field identifies, by (1-based) index, the nearest point in the geometry to the hit point.
• The distance field describes the distance from the hit point to the closest point on the shape part that was hit. (If no part was hit, this value is undefined.) If more than one shape part was hit, this is the distance to the first shape part encountered that was within the tolerance of the hit point. The order in which shape parts are examined during hit-testing is defined by the gxShapeParts enumeration.

ERRORS, WARNINGS, AND NOTICES

Because it performs many of the calculations involved in drawing, the GXHitTestShape function can post, in addition to the errors listed below, any
errors and warnings associated with the GXDrawShape function. Therefore GXHitTestShape can post font-related errors if it is caching text.

Errors
out_of_memory
shape_is_nil
parameter_is_nil	(debugging version)
number_of_contours_exceeds_implementation_limit
number_of_points_exceeds_implementation_limit
size_of_polygon_exceeds_implementation_limit
size_of_path_exceeds_implementation_limit
size_of_bitmap_exceeds_implementation_limit
pattern_lattice_out_of_range	(debugging version)
Warnings
character_substitution_took_place
graphic_type_cannot_be_dashed	(debugging version)
unable_to_traverse_open_contour_that_starts_or_ends_off_the_curve
	(debugging version)
unable_to_draw_open_contour_that_starts_or_ends_off_the_curve
	(debugging version)
face_override_style_font_must_match_style	(debugging version)

SEE ALSO

Hit-testing is discussed in the section "Drawing and Hit-Testing Shapes" beginning on page 2-35.

The gxHitTestInfo structure is described on page 2-50.

The gxShapeParts enumeration and the gxShapePart mask are also described in the hit-test parameters section of the chapter "Transform Objects" in this book.